home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 February / EnigmA AMIGA RUN 04 (1996)(G.R. Edizioni)(IT)[!][issue 1996-02][Skylink CD III].iso / earcd / comm2 / rpgbbs3.lha / Documentation / XEM_structure < prev    next >
Text File  |  1992-07-12  |  13KB  |  296 lines
  1.  
  2.                      /** XEm structure description **/
  3.  
  4.      (with parts from XPr-Documentation  written by W.G.J. Langeveld)
  5.  
  6.  
  7.  
  8. LONG (*xem_sread)();    /* very similar to xpr_sread */
  9. --------------------
  10.  
  11.   The xem_sread() call-back function has the following calling sequence:
  12.  
  13.      LONG count = (*xem_sread)(UBYTE *buffer, LONG size, LONG timeout)
  14.            D0                        A0            D0         D1
  15.  
  16. The first argument is a pointer to a buffer to receive the characters from the
  17. serial port, with a size specified in the second argument. The third item is a
  18. timeout in microseconds. The function returns the actual number of characters
  19. put into the buffer, or -1L on error. When the timeout argument is non-zero, the
  20. function will return when one of three events occurs: (1) the timeout period
  21. has expired, or (2) the buffer has been filled with  exactly "size" characters,
  22. or (3) an error occurs.
  23.         Specifically, when the routine is called, a timer is started and set to
  24. the value contained in timeout. The routine now starts collecting data from the 
  25. serial port and stores them in buffer. If the timer times out before size
  26. characters are received, the routine returns immediately with count set to the
  27. actual number of characters received. In case no characters at all are received,
  28. it will return count = 0L. If the buffer is full before the timer has expired,
  29. the routine returns immediately with count = size. It is up to the xem to set
  30. the  timeout long enough to ensure that at the current baud rate the buffer can
  31. actually be filled to the specified size within the timeout period. The routine
  32. can also return with count set to -1L. This might happen, for example, when the
  33. carrier is lost. The xem should then fairly quickly get around to checking
  34. the abort status using the xem_chkabort() function: BBS programs will want to
  35. regain control quickly after the carrier is dropped.
  36.         The timeout may be set to 0L if the objective is to just read any
  37. characters that may currently be available. In this case, the function will not
  38. start up a timer, but will instead check the serial device for currently
  39. available characters and return them in the usual fashion, and return as quickly
  40. as possible. Note: the value 0L for the timeout argument is a special case.
  41. Remember that AmigaDOS 1.3 may have problems with small non-zero values for
  42. timeouts.
  43.  
  44.  
  45.  
  46. LONG (*xem_swrite)();    /* very similar to xpr_swrite() */
  47. ---------------------
  48.  
  49. The xem_swrite() call-back function has the following calling sequence:
  50.  
  51.   LONG status = (*xem_swrite)(UBYTE *buffer, LONG size)
  52.        D0                           A0          D0
  53.  
  54. This function writes a buffer with the given size to the serial port.
  55. It returns 0L on success, non-zero on failure.
  56.  
  57.  
  58.  
  59. LONG (*xem_sflush)();    /* very similar to xpr_sflush() */
  60. ---------------------
  61.  
  62. The xem_sflush call-back function has the following calling sequence:
  63.  
  64.   LONG status = (*xem_sflush)()
  65.       D0
  66.  
  67. This function flushes all the data in the serial port input buffer.  It is
  68. typically used to recover after a read/write error.
  69. The function returns 0L on success, non-zero on failure.
  70.  
  71.  
  72.  
  73. LONG (*xem_sbreak)();
  74. ---------------------
  75.  
  76. The xem_sbreak call-back function has the following calling sequence:
  77.  
  78.   LONG status = (*xem_sbreak)()
  79.       D0
  80.  
  81. This function sends a break signal across the serial line.
  82. The function returns 0L on success, non-zero on failure.
  83.  
  84.  
  85.  
  86. LONG  *xem_squery();
  87. --------------------
  88.  
  89. The xem_squery call-back function has the following calling sequence:
  90.  
  91.         LONG size = (*xem_squery)()
  92.           D0
  93.  
  94. This function returns the number of characters currently available
  95. in the serial device. It returns -1L on error. When no characters
  96. are available the function returns 0L.
  97.  
  98.  
  99. VOID *xem_sstart();
  100. -------------------
  101.  
  102. The xem_sstart call-back function has the following calling sequence:
  103.  
  104.       VOID (*xem_sstart)(VOID);
  105.  
  106. This function tells the comm program to restart the serial read activity.
  107.  
  108.  
  109.  
  110. BOOL (*xem_sstop)();
  111. --------------------
  112.  
  113. The xem_sstop call-back function has the following calling sequence:
  114.  
  115.       BOOL (*xem_sstop)(VOID);
  116.  
  117. This function tells the comm program to stop the serial read activity.
  118. After this call, the xem owns the serial line. This function enables
  119. the xem to startup external protocols (xpr).
  120. The function returns 0L on success, non-zero on failure.
  121.  
  122.  
  123.  
  124. VOID *xem_tbeep();
  125. ------------------
  126.  
  127. The xem_tbeep call-back function has the following calling sequence:
  128.  
  129.       VOID (*xem_tbeep)(ULONG ntimes, ULONG delay);
  130.  
  131. This function tells the comm program to perform a user-preferred
  132. DisplayBeep. This beep should be done `ntimes' with a `delay' between
  133. each beep.
  134.  
  135.  
  136.  
  137. LONG (*xem_tgets)();
  138. --------------------
  139.  
  140. The xem_tgets call-back function has the following calling sequence:
  141.  
  142.         LONG status = (*xem_tgets)(UBYTE *prompt, UBYTE *buffer)
  143.              D0                        A0             A1
  144.  
  145. The first argument is a pointer to a string containing a prompt, to be displayed
  146. by the communications program in any manner it sees fit. The second argument
  147. should be a pointer to a buffer to receive the user's response. The third
  148. argument is the size of the buffer in bytes.
  149. The function returns 0L on failure or user cancellation, non-zero on success.
  150. The buffer has to be supplied by the xem.
  151.  
  152.  
  153.  
  154. LONG  *xem_options();    /* 100% compatible to xpr_options */
  155. ---------------------
  156.  
  157.       LONG status = (*xem_options)(LONG n, struct xem_option *opt[])
  158.             D0                       D0               A0
  159.  
  160. The function passes to the comm program a pointer to an array of n pointers to
  161. xem_option structures, where n is limited to 31. The xem_option structures are
  162. defined as follows:
  163.  
  164. struct xem_option {
  165.    char *xemo_description;      /* description of the option                  */
  166.    long  xemo_type;             /* type of option                             */
  167.    char *xemo_value;            /* pointer to a buffer with the current value */
  168.    long  xemo_length;           /* buffer size                                */
  169. }
  170.  
  171. Valid values for xemo_type are:
  172.  
  173. #define XEMO_BOOLEAN 1L         /* xemo_value is "yes", "no", "on" or "off"   */
  174. #define XEMO_LONG    2L         /* xemo_value is string representing a number */
  175. #define XEMO_STRING  3L         /* xemo_value is a string                     */
  176. #define XEMO_HEADER  4L         /* xemo_value is ignored                      */
  177. #define XEMO_COMMAND 5L         /* xemo_value is ignored                      */
  178. #define XEMO_COMMPAR 6L         /* xemo_value contains command parameters     */
  179.  
  180.         The array is allocated and initialized by the xem to default values. If
  181. the comm program implements this function, it should display the description of
  182. the option and its current value to the user and allow him/her to change them.
  183. This could be accomplished either by dynamically building a requester or by
  184. displaying each line one at a time and allow the user to enter new values or
  185. accept the default. Options that have boolean values could be implemented by the
  186. comm program as boolean gadgets, but the new value must be returned as "yes" or
  187. "on" for logical 1 or "no" or "off" for logical 0 in the xemo_value buffer.
  188. Note, that the xem, if it uses this function must recognize both "yes" and "on"
  189. for logical 1 and "no" and "off" for logical 0. Long values must if necessary be
  190. converted to a string and copied to the xemo_value buffer.  For options that
  191. have string values, the comm program must ensure that the new string selected by
  192. the user fits in the value buffer as determined by the xemo_length field. The
  193. buffer is supplied by the xem, and must be large enough to be able to hold the
  194. '\0' termination.
  195.         The option of type XEMO_HEADER contains a pointer to an explanatory
  196. message in its xemo_description field. It is to be interpreted as a header
  197. string for the options that follow. It has no other function, any bits
  198. corresponding to this option in the return value should be ignored, and the
  199. xem_value string is meaningless, but should be initialized to either NULL or a
  200. valid pointer to a buffer. The message should have a length of 50 characters or
  201. less.
  202.         The options of type XEMO_COMMAND and XEMO_COMMPAR are used for such
  203. functions as a main menu. Simple commands (XEMO_COMMAND) could be
  204. displayed as boolean gadgets in a requester, while commands needing parameters
  205. could have an associated string gadget. The difference between commands like
  206. this and other options is that when one of these commands is selected, the
  207. requester should disappear and xem_options() should return immediately, with
  208. only the bit coresponding to the command set. Therefore, ideally, the xem should
  209. not mix XEMO_COMMAND/XEMO_COMMPAR options with other options (except of type
  210. XEMO_HEADER). Rather, the xem should first call xem_options() with only 
  211. XEMO_COMMAND/XEMO_COMMPAR/XEMO_HEADER options, one of which would be a "Change
  212. Defaults" command (type XEMO_COMMAND). This command, when selected, would cause
  213. the xem to call xem_options() with a list of other xem_option structures for
  214. non-commands and their headers. This way, the communications program would
  215. automatically list the xem commands first, and one of the commands would be a
  216. "Change Defaults" command, which when selected by the user would bring up a
  217. second requester with the various other options supported by the xem. For simple
  218. commands, the xem_value string is meaningless and should either be set to NULL
  219. or contain a valid pointer to a buffer anyway. For commands needing parameters,
  220. the xem_value string should contain the current default value of the parameter.
  221.  
  222.         As an example, when selecting a VT based xem the following array of
  223. xem_option structures could be passed to the comm program:
  224.  
  225. xemo_description                xemo_value    xemo_type
  226. --------------------------------------------------------------
  227. Newline mode                    no            XEMO_BOOLEAN
  228. Insert mode                     yes           XEMO_BOOLEAN
  229. Wrap mode                       no            XEMO_BOOLEAN
  230. Cursor visible                  yes           XEMO_BOOLEAN
  231. Smooth scroll                   no            XEMO_BOOLEAN
  232. Answer-back msg                 foobar        XEMO_STRING
  233.  
  234. Notice again, that the COMM program still knows little about the individual
  235. option items (and in fact there is no way for it to find out, in keeping with
  236. the philosophy of xem). Also notice that a cheap way to implement this function
  237. is to loop over the n supplied xem_option's and to call the likely already
  238. implemented xem_gets function with the option description and the value buffer
  239. (but remember that some options may not have valid value buffers!).
  240.         It is important to follow a few rules when calling this function: the
  241. description strings should be 25 characters or less (except for XEMO_HEADER's).
  242. The value strings can be any length up to 255 characters, but be aware that in a
  243. typical situation only about 10 to 15 of them will be displayed in a string
  244. gadget.
  245.         The return value, status, reflects which options have changed by having
  246. the corresponding bit set. The first option in the xem_option array corresponds
  247. to  bit 0 (low-order), etc. If the options are all of the types boolean, long,
  248. string or header, the comm program may decide to not detect whether the options
  249. changed or not, and 0x07FFFFFFL may be returned, in effect specifying that all
  250. options have changed. On the other hand, if the communications program returns
  251. a value with multiple bits set even though some or all of the options are of
  252. type command, the xem should be careful to cause minimal damage, or display
  253. an error message.
  254. If nothing changed or no command was selected, 0L is returned.
  255. If an error occurred, the function returns -1L.
  256.  
  257.  
  258.  
  259. LONG (*xem_process_macrokeys)();
  260. --------------------------------
  261.  
  262. The xem_xem_process_macrokeys call-back function has
  263. the following calling sequence:
  264.  
  265.    LONG status = (*xem_xem_process_macrokeys)(struct XEmulatorMacroKey *key)
  266.         D0                                             A0
  267.  
  268. the xem has matched a key attached in the macrokey list. The comm program
  269. is now requested to dispatch this key. This can happen in various
  270. variants:
  271. 1: there could be a function pointer key->xmk_UserData to handle
  272.    this specific key; e.g. XON/XOFF handling.
  273. 2: The comm program could take the key->xmk_Code as an index and
  274.    use it in a string array.
  275.  
  276. struct XEmulatorMacroKey {
  277.   struct MinNode xmk_Node;
  278.   UWORD    xmk_Qualifier;    /* see below */
  279.   UBYTE    xmk_Type;    /* see below */
  280.   UBYTE    xmk_Code;    /* raw or cooked key-code */
  281.   APTR    xmk_UserData;    /* comm-proggy private data */
  282.             /* could be a function ptr or a modem cmd */
  283. };
  284.  
  285. /*----- Qualifiers for XMK_QUALIFIER -----*/
  286. #define XMKQ_NONE      0 /* execute this key if no qualfier is pressed */
  287. #define XMKQ_SHIFT     1 /* execute this key if a shift key is pressed */
  288. #define XMKQ_ALTERNATE 2 /* execute this key if  an alt key is pressed */
  289. #define XMKQ_CONTROL   3 /* execute this key if control key is pressed */
  290.  
  291. /*----- Types for XMK_TYPE -----*/
  292. #define XMKT_IGNORE 1    /* ignore this key definition */
  293. #define XMKT_RAWKEY 2    /* xmk_Code is raw */
  294. #define XMKT_COOKED 3    /* xmk_Code is cooked */
  295.  
  296.